/* Copyright (c) 2009, Enric Rodriguez (enrodri86@gmail.com)
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 	- Redistributions of source code must retain the above copyright
 * 	notice,	this list of conditions and the following disclaimer.
 * 	- Redistributions in binary form must reproduce the above copyright
 * 	notice, this list of conditions and the following disclaimer in the
 * 	documentation and/or other materials provided with the distribution.
 * 	- Neither the name of the <ORGANIZATION> nor the names of its
 * 	contributors may be used to endorse or promote products derived from
 * 	this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
package es.enrodri86.mmo.auth.client;

import java.io.IOException;
import java.util.List;

import es.enrodri86.mmo.auth.shared.AuthException;
import es.enrodri86.mmo.auth.shared.Captcha;
import es.enrodri86.mmo.auth.shared.Game;
import es.enrodri86.mmo.auth.shared.GameServer;
import es.enrodri86.mmo.auth.shared.LoginException;

/**
 * This interface represents any kind of connection to an authentication
 * server. In principle, only HTTPS implementation would be available but
 * developers might want to do other implementations like SSL sockets, or plain
 * TCP sockets.
 *
 * This class will be passed to the GUI packages and should be used like this:
 *
 * <code>
 * AuthConnection conn = new HTTPSAuthConnection("https://host:port/context/servlet");
 *
 * [... passing AuthConnection to GUI classes ...]
 *
 * try{
 *	conn.connect();
 *	if(conn.isCaptchaRequired()){
 *		conn.getCaptcha();
 *		[... show JPanel with captcha ...]
 *	}
 *	[... user input ...]
 *	conn.login(user,pass,captcha);
 *
 *	if(conn.isGameSelectionRequired()){
 *		GameList gl = conn.getGameList();
 *		[... user input ...]
 *		conn.chooseGame(gl.get(glindex));
 *	}
 *
 *	ServerList sl = conn.getServerList();
 *	[... user input ...]
 *	conn.chooseServer(sl.get(slindex));
 *
 *	String session = conn.getSession();
 *
 *	[... connect to game server and send session ...]
 * }catch(Exception e){}
 *
 * </code>
 * @author enrodri86
 */
public interface AuthConnection {

	public void connect() throws IOException, AuthException;

	public boolean isCaptchaRequired();

	public Captcha getCaptcha();

	public boolean login(String user, char[] pass, String captcha) throws LoginException;

	public boolean isGameSelectionRequired();

	public List<Game> getGameList();

	public void chooseGame(Game g) throws IOException, AuthException;

	public List<GameServer> getGameServerList();

	public void chooseGameServer(GameServer gs) throws IOException, AuthException;

	public String getSession();

}
